Bug Proofing Visual Basic: A Guide to Error Handling and Prevention
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471323519
Publication Date: 11/01/98

APPENDIX B
Header Comment Templates

This appendix contains templates for header-style comments. You can add them to your files and routines, and then fill in the blanks. You can download copies of these templates from the book’s Web site at www.vb-helper.com/err.htm.

Files

Remove any headings that you do not use in a particular file. For instance, if a .BAS module does not define any public variables, you should remove the public variable section.

‘ ************************************************
‘ File:
‘ Copyright:
‘
‘ Date Created:
‘ Initial Author:
‘
‘ Purpose:
‘
‘ Entry Points:
‘
‘ Dependencies:
‘
‘ Issues:
‘
‘ Method:
‘ ************************************************
Option Explicit

‘ ************************************************
‘ Global Definitions
‘ ---------------------------
‘ Global API Declarations
‘ ---------------------------

‘ ---------------------------
‘ Global Types
‘ ---------------------------

‘ -
‘ Global Enums and Constants
‘ ---------------------------

‘ ---------------------------
‘ Global Variables
‘ ---------------------------

‘ ************************************************
‘ Private Definitions
‘ ---------------------------
‘ Private API Declarations
‘ ---------------------------

‘ ---------------------------
‘ Private Types
‘ ---------------------------

‘ ---------------------------
‘ Private Constants and Enums
‘ ---------------------------

‘ ---------------------------
‘ Private Variables
‘ ---------------------------

Routines

You may want to leave in sections in these comments even if they do not apply to a particular routine. For example, if a function takes no parameters, you may want to use the following comment to make it clear that the input section is blank and not accidentally omitted.

‘ Inputs:
‘    None.

Some programmers place a routine’s comments after its declaration and before any variable declarations. It does not matter where you place the comments, as long as you are consistent.

‘ ************************************************
 ‘ Purpose:
‘
‘ Method:
‘
‘ Inputs:
‘
‘ Outputs:
‘
‘ Errors:
‘
‘ Asserts:
‘
‘ Developer           Date     Comments
‘ ---------           -------- --------
‘
‘ ************************************************

Event Handlers

Experienced programmers are familiar with the parameters of most common event handlers, so the comments do not need to explain them. A reader with questions can consult Visual Basic’s online help

One exception to this rule is if the event handler has side effects. For example, if the routine updates a global variable, that information should be listed in the output section.

‘ ************************************************
 ‘ Purpose:
‘ Method:
‘
‘ Outputs:
‘
‘ Asserts:
‘
‘ Developer           Date     Comments
‘ ---------           -------- --------
‘
‘ ************************************************